% \iffalse meta-comment
%%
%% prettyref v1.0
%%
%% Copyright 1995.  by Kevin Ruland kevin@rodin.wustl.edu
%%
%    \begin{macrocode}
%<*driver>
\documentclass{ltxdoc}
\usepackage{doc}
\CodelineNumbered
\begin{document}
  \DocInput{prettyref.dtx}
\end{document}
%</driver>
%    \end{macrocode}
%
% \fi
%
% \iffalse
%<*style>
% \fi
%
% \title{Improved reference formatting for \LaTeX2e}
%
% \author{Kevin S. Ruland}
%
% \maketitle
%
% This package provides additional functionality to \LaTeX2e label--reference
% mechanism.   It allows the author to ``preformat'' all types of labels.
%
% A long standing problem with \LaTeX\ |\ref| command is that it only
% provides a raw number.  The author is responsible for properly formatting
% the number correctly.  For example, in order to correctly format a reference
% to an equation, the author must use |\textup{(\ref{eq:1})}|.  Or similarly
% for a figure, |Figure~(\ref{fig:2})|.  This way the ``format'' of the
% reference is hard coded into the paper.  If the author decides to change
% figure references to |Figure~\ref{fig:2}|, she must search and replace all
% the strings in the tex source.
%
% AMS\LaTeX\ has partially addressed this problem by providing the package
% |upref| and command |\eqref| in |amsmath|.  This is a partial solution
% for equation numbers and forces equation numbers in upright style.
%
% This package provides a more comprehensive solution by allowing the author
% to define various formats for the labels.  For example, to label a
% table the author would use |\label{tab:1}[table]|.  To access the formatted
% reference the author uses |\prettyref{tab:1}|.
%
% If the optional argument to |\label| is missing, the default format is
% an equation.  This is done because |amsmath| calls |\label| directly
% for equations.  The optional argument allows this package to work in
% conjunction with |amsmath|.  However, |\usepackage{prettyref}| must precede
% |\usepackage{amsmath}| because |amsmath| stores away the previous definition
% of |\label| (this one) and redefines it.
%
% This package functions by changing the way \LaTeX\ ``stores'' labels in
% the |.aux| file.  When \LaTeX\ processes a |\label| command it, after
% checking if it was previously defined, writes a line to the |.aux| file
% such as:
% \begin{verbatim}
%  \newlabel{<label>}{{<count>}{<pageno>}}
% \end{verbatim}
% Where |<count>| is
% the value of the pertinent counter, and |<pageno>| is the page number.
% These two pieces of data are returned by the commands |\ref{<label>}|
% and |\pageref{<label>}|, respectively.
%
% When using this package, the |\label| command writes a line such as
% \begin{verbatim}
%  \newlabel{<label>}{{<count>}{<pageno>}{<formatted label>}}
% \end{verbatim}
% to the |.aux| file.  The |<formatted label>| portion is created by
% formatting |<count>| and |<pageno>| according to the proper reference
% format.  |\ref| and |\pageref| work as usual and |\prettyref| is
% added to return |<formatted label>|.
%
% There is one problem with this package.  The label formatting routines
% do not check if the appropriate format is defined.  If |\label| is
% called with an undefined format, then mysterious error messages will
% result.
% 
%    \begin{macrocode}
\ProvidesPackage{prettyref}
%    \end{macrocode}
%
% Declare some auxiliary functions to access the reference data structure.
%
%    \begin{macrocode}
\long\def\@firstofthree#1#2#3{#1}
\long\def\@secondofthree#1#2#3{#2}
\long\def\@thirdofthree#1#2#3{#3}
%    \end{macrocode}
%
% The default formats for table, eq, lemma, thm, section, and figure.
% 
% Each |\pr@<format>| is given two arguments, the count and page number.
% |\pr@<format>| is called by |\label{<label>}[<format>]|.
%
% A user accessible function should be defined
% to change/add formats to these.
%
%    \begin{macrocode}
\def\pr@table#1#2{Table #1}
\def\pr@eq#1#2{\textup{(#1)}}
\def\pr@lemma#1#2{Lemma #1}
\def\pr@thm#1#2{Theorem #1}
\def\pr@section#1#2{Section #1}
\def\pr@figure#1#2{Figure #1}
%    \end{macrocode}
%
% This is \LaTeX2e |\@setref|.  It is included here to make sure no previously
% included styles have changed it.  For example, AMS\LaTeX's |upref| redefines
% it, but this package is much better.
%
%    \begin{macrocode}
\def\@setref#1#2#3{%
  \ifx#1\relax
   \protect\G@refundefinedtrue
   \nfss@text{\reset@font\bfseries ??}%
   \@latex@warning{Reference `#3' on page \thepage \space
             undefined}%
  \else
   \expandafter#2#1\null
  \fi}
%    \end{macrocode}
%
% \DescribeMacro{\ref}
% \DescribeMacro{\pageref}
% \DescribeMacro{\prettyref}
% These are the access routines to the various portions of the label
% structure
%
%    \begin{macrocode}
\def\ref#1{%
  \expandafter\@setref\csname r@#1\endcsname\@firstofthree{#1}}
\def\pageref#1{%
  \expandafter\@setref\csname r@#1\endcsname\@secondofthree{#1}}
\def\prettyref#1{%
  \expandafter\@setref\csname r@#1\endcsname\@thirdofthree{#1}}
%    \end{macrocode}
%
% These actually changes the way the |\newlabel| command is written to the 
% |.aux| file.  |\label| is redefined to take a trailing optional argument
% which defines the format for this pretty reference.
%
% \DescribeMacro{\@prettylabel}
% If |\label| is called with the optional arguement then |\@prettylabel|
% writes the line to the |.aux| file.
%
%    \begin{macrocode}
\def\@prettylabel#1[#2]{
  \@bsphack
  \protected@write\@auxout{}%
    {\string\newlabel{#1}%
     {{\@currentlabel}{\thepage}%
      {\csname pr@#2\endcsname\@currentlabel\thepage}}}%
  \@esphack}
%    \end{macrocode}
%
% \DescribeMacro{\@noprettylabel}
% If |\label| is called without the optional arguement then |\@noprettylabel|
% writes the line to the |.aux| file.
%
%    \begin{macrocode}
\def\@noprettylabel#1{
  \@bsphack
  \protected@write\@auxout{}%
    {\string\newlabel{#1}%
     {{\@currentlabel}{\thepage}%
      {\pr@eq\@currentlabel\thepage}}}%
  \@esphack}
%    \end{macrocode}
%
% \DescribeMacro{\label}
% The user's |\label| command simply checks for the existance of the
% optional arguement and calls one of |\@prettylabel| or |\@noprettylabel|.
% Unfortunately, |amsmath| redefines |\label| too.  In order for this package
% to work with |amsmath|, |\usepackage{prettyref}| must be included before
% |\usepackage{amsmath}|
%
%    \begin{macrocode}
\def\label#1{
	\@ifnextchar[{\@prettylabel{#1}}{\@noprettylabel{#1}}
}
%    \end{macrocode}
%
% \endinput
%
\endinput
%</style>
%
